home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / MANUALS / STRONGHELP / DRAWFILE / DrawFile / ReadMe < prev   
Text File  |  1995-01-18  |  9KB  |  272 lines
  1. DrawFile 1.4
  2. ======== ===
  3.  
  4.    This directory contains the specification for the DrawFile module (below),
  5. and headers for C and assembler, and a veneer library, all in OSLib format.
  6. The OSLib header file also contains all the structure definitions you might
  7. need to manipulate draw files in C.
  8.  
  9.    DrawFile is a module that renders draw files. It provides three SWI's, two
  10. service calls and a *command. Version numbers in [square brackets] are the
  11. earliest version to implement a given feature.
  12.  
  13. SWI's
  14. =====
  15.  
  16. DrawFile_Render
  17. ---------------
  18.  
  19. Entry:
  20.  
  21.    R0    =  flags:
  22.                bit 0: render bounding boxes (as dotted red rectangles)
  23.                bit 1: do not render the objects themselves
  24.                bit 2: if set, R5 is used as the flatness parameter [1.3]
  25.    R1    -> draw file data
  26.    R2    =  size of draw file in bytes
  27.    R3    -> transformation matrix
  28.          =  0 <=> use identity
  29.    R4    -> clipping rectangle in O S units
  30.          =  0 <=> no clipping rectangle set up
  31.    R5    =  flatness with which to render lines (if bit 2 of R0 set) [1.3]
  32.  
  33. Exit:
  34.  
  35.    All registers preserved
  36.  
  37. Use:
  38.  
  39.    This SWI renders a draw file at a given screen position where that
  40. position is defined as screen position 0, 0 with the x- and y-translations
  41. as specified in the transformation matrix. Hence to render a non-rotated 1:1
  42. draw file at (x, y) (screen coordinates in O S units) the transformation
  43. matrix is
  44.  
  45.       (1 << 16        0)
  46.       (      0  1 << 16)
  47.       (  256*x    256*y).
  48.  
  49. The effects of calling the module with the matrix not of the form
  50.  
  51.       (f  0)
  52.       (0  f)
  53.       (x  y)
  54.  
  55. (which is a translation and a magnification) should not be relied on. If R3
  56. = 0, then unit transformation matrix is assumed (i e, the draw file is
  57. rendered with its bottom left corner at screen coordinates (0, 0)).
  58.  
  59.    The clipping rectangle is typically a redraw rectangle returned by the
  60. Wimp on a redraw window request.  If R4 = 0, then the whole draw file is
  61. rendered. If non-zero, only objects which intersect the clipping rectangle
  62. are rendered.
  63.  
  64. DrawFile_BBox
  65. -------------
  66.  
  67. Entry:
  68.  
  69.    R0    =  flags (must be 0)
  70.    R1    -> draw file data
  71.    R2    =  size of draw file in bytes
  72.    R3    -> transformation matrix
  73.          =  0 <=> use identity
  74.    R4    -> 4-word buffer to hold the bounding box of the draw file
  75.             (x0, y0, x1, y1) in draw units
  76.  
  77. Exit:
  78.  
  79.    All registers preserved. Buffer pointed at by R4 holds the bounding box
  80. of the draw file (x0, y0, x1, y1) in draw units.
  81.  
  82. Use:
  83.  
  84.    This SWI is used to determine the bounding box (in draw units) of the
  85. given draw file, as if it were plotted with the transformation given.
  86.  
  87. DrawFile_DeclareFonts
  88. ---------------------
  89.  
  90. Entry:
  91.  
  92.    R0    =  flags
  93.                bit 0: do not download font (passed to PDriver_DeclareFont)
  94.    R1    -> draw file data
  95.    R2    =  size of draw file in bytes
  96.  
  97. Exit:
  98.  
  99.    All registers preserved. All fonts used by the document have been
  100. declared.
  101.  
  102. Use:
  103.  
  104.    If a printer requires font declarations, this SWI must be called for each
  105. drawfile to be printed, between the calls to PDriver_SelectJob and
  106. PDriver_DrawPage.
  107.  
  108.    All fonts are declared as "kerned," since this includes the non-kerned
  109. case.
  110.  
  111. Service calls
  112. ======= =====
  113.  
  114. Service_DrawObjectRender (SWI 0x30) [1.4]
  115.  
  116. Entry:
  117.  
  118.    R0 = object type
  119.    R1 = 0x45540 (reason code)
  120.    R2 -> render state block
  121.  
  122. Exit:
  123.  
  124.    R1 = 0 if claimed, otherwise preserved
  125.  
  126. Use:
  127.  
  128.    This service call is made when SWI DrawFile_Render encounters an object
  129. with a type it doesn't recognise, so that another module may render it
  130. instead. It should be claimed if the object type is recognised. If an error
  131. is encountered during rendering, an OS_Error pointer may be put in the
  132. DrawFile_RenderState structure, but this should only be done if the pointer
  133. currently there is 0. The DrawFile module will attempt to render all objects,
  134. but only return the first error found. The block is defined as 
  135.  
  136.    +0    -> object to be rendered
  137.    +4    -> diagram
  138.    +8    -> font table object, or 0 if none found yet
  139.    +12   = flags, as passed to DrawFile_Render
  140.    +16   => transformation matrix
  141.    +20   -> clipping rectangle, or 0
  142.    +24   = flatness
  143.    +28   -> error block, or 0
  144.  
  145. Service_DrawObjectDeclareFonts (SWI 0x30) [1.4]
  146.  
  147. Entry:
  148.  
  149.    R0 = object type
  150.    R1 = 0x45541 (reason code)
  151.    R2 -> declare font dtate block
  152.  
  153. Exit:
  154.  
  155.    R1 = 0 if claimed, otherwise preserved
  156.  
  157. Use:
  158.  
  159.    This service call is made when DrawFile_DeclareFonts encounters an object
  160. with a type it doesn't recognise, so another module may declare its fonts
  161. instead. It should be claimed if the object type is recognised. If an error
  162. is encountered during rendering, an OS_Error pointer may be put in the
  163. DrawFile_DeclareFontsState structure, but this should only be done if the
  164. pointer currently there is 0. The DrawFile module will attempt to declare
  165. fonts for all objects, but only return the first error found. The block is
  166. defined as 
  167.  
  168.    +0    -> object to be rendered
  169.    +4    -> diagram
  170.    +8    -> font table object, or 0 if none found yet
  171.    +12   = flags, as passed to DrawFile_DeclareFonts
  172.    +16   -> error block, or 0
  173.  
  174. *Commands
  175. ---------
  176.    There is one *command, *Render, with syntax
  177.  
  178.       Render [-file] <filename> [<m00> <m01> <m10> <m11> <m20> <m21>]
  179.             [-bbox] [-suppress] [-flatness <flatness>]
  180.  
  181. It renders the given drawfile through the transformation specified. If -bbox
  182. is specified, bounding boxes are drawn as well. If -suppress is given, the
  183. objects themselves are not displayed, although the file is checked for
  184. consistency and bounding boxes (if requested) are. If a flatness argument is
  185. given (preceded by the keyword -flatness), this is passed to the draw
  186. module.
  187.  
  188.   All units for the *command are the natural ones. Decimal fractions may be
  189. specified if required, but negative numbers must be quoted because of
  190. limitations in OS_ReadArgs. The scaling is:
  191.  
  192.       m00 m01 m10 m11:  0x10000
  193.       m20 m21:          256
  194.       flatness          256
  195.  
  196.    For example, to render a draw file F at 1.5 times zoom, with a flatness of
  197. 0.5 O S units (128 draw units), the command is
  198.  
  199.       Render F 1.5 0 0 1.5 0 0 -flatness .5
  200.  
  201. Other information
  202. ---- ------------
  203.  
  204.    The SWI chunk number of the DrawFile module is 0x45540 and its error base
  205. is 0x20C00. It has no vectors, upcalls or events.
  206.  
  207.    The errors it provides are
  208.  
  209.    Error_DrawFileNotDraw (0x20C00) The file is not a Draw file (as recognised
  210. by the first 4 characters 'D', 'r', 'a', 'w').
  211.    Error_DrawFileVersion (0x20C01) The file specifies a format version number
  212. which is not understood.
  213.    Error_DrawFileFontTab (0x20C02) The file contains more than one font
  214. table.
  215.    Error_DrawFileBadFontNo (0x20C03) A text line (or transformed text line)
  216. uses a font that is not in the font table object.
  217.    Error_DrawFileBadMode (0x20C04) The file contains a sprite defined in a
  218. mode which is not recognised.
  219.    Error_DrawFileBadFile (0x20C05) The size of an object in the file is
  220. larger than the size of the file allows.
  221.    Error_DrawFileBadGroup (0x20C06) The size of an object in a group is
  222. greater than the size of the group allows.
  223.    Error_DrawFileBadTag (0x20C07) The size of a tagged object's data is
  224. larger than the size of the tagged object allows.
  225.    Error_DrawFileSyntax (0x20C08) A text area has an illegal or unrecognised
  226. command sequence in it.
  227.    Error_DrawFileFontNo (0x20C09) An attempt was made to set a font (with a
  228. \<digit> command) which had no definition (\F command).
  229.    Error_DrawFileAreaVer (0x20C0A) The text area version command (\!) has
  230. specified a version which is not understood.
  231.    Error_DrawFileNoAreaVer (0x20C0B) There is a text area with no version
  232. (\!) command.
  233.  
  234. Notes
  235. =====
  236.  
  237.    There are some small differences between the output of the DrawFile
  238. module and Draw, as enumerated below:
  239.  
  240. Text
  241. ----
  242.  
  243.    A text line that uses a font which can't be found will be rendered (in
  244. system font) at a size to fit its bounding bound.
  245.  
  246. Transformed text
  247. ----------- ----
  248.  
  249.    Transformed text lines in system font are supported.  A transformed text
  250. line that uses a font which can't be found will be rendered (in system font)
  251. at a size to fit its bounding bound. The transformation will be ignored.
  252.  
  253. Text areas
  254. ---- -----
  255.  
  256.    In a text area, if you change (for example) the margin size (\M command),
  257. the change doesn't take effect until the next output line. In Draw, this
  258. refers to printable characters: but in DrawFile, it includes colour and font
  259. change commands as well. (This is because DrawFile uses the Font Manager to
  260. remember the current font and colours.) This means that line breaks can
  261. happen at slightly different places when using DrawFile.
  262.  
  263.    The following commands cause output to occur: B C U V <digits>. The
  264. following do not: ! ; A D F L M P. By preceding the former with the latter,
  265. the problem can be avoided.
  266.  
  267. Sprite colours
  268. ------ -------
  269.  
  270.    For a sprite without a palette, the colours used are the WIMP colours,
  271. found by using Wimp_ReadPalette. This would lead to inconsistent behaviour
  272. if the WIMP was not running on the machine.